Using the Toggle Button Group nodes

Use the Toggle Button Group nodes to allow users to select only one option from a set of options that are mutually exclusive. Toggle buttons in a toggle button group behave like radio buttons, where only one toggle button can be active at a time. Use Toggle Button Group 3D to group 3D toggle buttons in 3D space, and Toggle Button Group 2D to group 2D toggle buttons in 2D space.

A toggle button group is an object that can contain toggle buttons and manages the states of its toggle buttons, but does not provide a visual shape.
When a Toggle Button node in a Toggle Button Group has focus, it receives click input from the keyboard keys Space, Enter, and Enter on the numeric pad by default. Use scripting functions to get and set the node that currently has focus in the project. See Scripting reference and Using triggers.

Creating a toggle button group

To create a toggle button group:

In the Project press Alt and right-click the node where you want to create a toggle button group and select either Toggle Button Group 3D, or Toggle Button Group 2D.
Note that you can create a 3D node only inside 3D nodes, and 2D node only inside 2D nodes.
In the Project in the toggle button group create a layout that arranges the toggle buttons in the toggle button group node.
For example, if you created a 3D toggle button group, create a Stack Layout 3D node, if you created a 2D toggle button group, create a Stack Layout 2D. See Using the Stack Layout nodes.
In the Project > Prefabs create a toggle button prefab and drag several toggle button prefabs from the Project > Prefabs to the layout inside the toggle button group to instantiate them in the toggle button group. See Using the Toggle Button nodes and Using prefabs.
For example, if you created a 3D toggle button group, create a Toggle Button 3D that contains a Text Block 3D. If you created a 2D toggle button group, create a Toggle Button 2D that contains a Text Block 2D.
In the Project select the toggle button prefab and in the Properties click and add to the toggle button the Index in Group property.
Kanzi uses the Index in Group property to keep track of which button is selected in a Toggle Button Group node. When the value of the Index in Group property is -1 the Toggle Button Group node sets the index for that Toggle Button.
Create a state manager that defines the toggle button in each state. See Creating state managers.
For example, create a state manager with two states that use the Toggle State property as their Controller Property, and define that when the Toggle State is 0 the text in the toggle button reads Off, and when Toggle State state is 1 the text reads On.
In the Project select the toggle button prefab, in the Properties add the State Manager property, and set it to the state manager you created in the previous step.
In the Preview when you click the visual representation of the toggle buttons in the toggle button group, notice how only one button can be active at a time.

Adding triggers to a toggle button group

To add a trigger to a toggle button group:

In the Project select the toggle button group to which you want to add a trigger. See Creating a toggle button group.
In the Node Components > Triggers section right-click, select Add Trigger, and select a trigger that intercepts the type of message you want to intercept.
For example, to add a trigger that is set off when a button in the toggle button group is toggled on, add the Toggle Button Group: Toggled trigger.
In the Node Components > Triggers section click the Add dropdown menu for the trigger you added in the previous step and select an action.
For example, select the Write Log action and enter a message you want to write to the Log window when the trigger is set off. The Write Log action is useful when you want to verify that the node received the input.
To make the Toggle Button Group: Toggled trigger intercept messages from all toggle buttons in the toggle button group, in the Node Components under the Toggle Button Group: Toggled trigger, click Trigger Settings, and in the Trigger Settings Editor, set Message Source to <No Item>.
Use the Message Source property to set which trigger messages this trigger handles. See Setting the handling of trigger messages.
Now when you toggle any of the buttons in the toggle button group, Kanzi prints to the Log window the message you entered as the value of the Log Message property.
To open the Log window, in the main menu select Window > Log.

Setting the appearance of a Toggle Button Group 2D node

To set the appearance of 2D nodes:

You can fill 2D nodes with a solid color, a texture, or a material. See Adjusting the appearance of 2D nodes.
You can rotate a 2D node around all three axes to create a 3D perspective effect. See Creating a 3D perspective effect for 2D nodes.
You can apply custom rendering to 2D nodes to create post-processing effects. See Applying custom rendering to 2D nodes.

Using the Toggle Button Group 3D node in the API

To create a Toggle Button Group 3D node with three toggle buttons:

// Create a Toggle Button Group 3D named Toggle button group and add it to the scene.
ToggleButtonGroup3DSharedPtr toggleButtonGroup3D = ToggleButtonGroup3D::create(domain, "Toggle button group");
scene->addChild(toggleButtonGroup3D);
// Create a Stack Layout 3D named Stack layout and add it to the Toggle button group.
// This stack layout is used only for arranging the items in the Toggle button group.
StackLayout3DSharedPtr stackLayout3D = StackLayout3D::create(domain, "Stack layout");
toggleButtonGroup3D->addChild(stackLayout3D);

// Create three toggle buttons and add them to the Stack layout.
ToggleButton3DSharedPtr buttons[3];

for (kzUint i = 0; i < 3; ++i)
{
    buttons[i] = ToggleButton3D::create(domain, "Toggle button");
    // Setting the Button Group Index property to -1, which tells the Toggle button group
    // to set the index of the toggle button.
    buttons[i]->setIndexInGroup(-1);
    stackLayout3D->addChild(buttons[i]);
}

// Print the index of the toggled button to show that the last button is toggled.
std::cout << toggleButtonGroup3D->getCurrentButtonIndex() << endl;

// Toggle the first toggle button.
buttons[0]->setToggleState(1);

// Print the index of the toggled button to show that the first button is toggled.
std::cout << toggleButtonGroup3D->getCurrentButtonIndex() << endl;

For details, see the ToggleButtonGroup3D class in the API reference.

Using the Toggle Button Group 2D node in the API

To create a Toggle Button Group 2D node with three toggle buttons:

// Create a Toggle Button Group 2D named Toggle button group and add it to the scene.
ToggleButtonGroup2DSharedPtr toggleButtonGroup2D = ToggleButtonGroup2D::create(domain, "Toggle button group");
viewportNode->addChild(toggleButtonGroup2D);
// Create a Stack Layout 2D named Stack layout and add it to the Toggle button group.
// This stack layout is used only for arranging the items in the Toggle button group.
StackLayout2DSharedPtr stackLayout2D = StackLayout2D::create(domain, "Stack layout");
toggleButtonGroup2D->addChild(stackLayout2D);

// Create three toggle buttons and add them to the Stack layout.
ToggleButton2DSharedPtr buttons[3];

for (kzUint i = 0; i < 3; ++i)
{
    buttons[i] = ToggleButton2D::create(domain, "toggle button");
    // Setting the Button Group Index property to -1, which tells the Toggle button group
    // to set the index of the toggle button.
    buttons[i]->setIndexInGroup(-1);
    stackLayout2D->addChild(buttons[i]);
}

// Print the index of the toggled button to show that the last button is toggled.
std::cout << toggleButtonGroup2D->getCurrentButtonIndex() << endl;

// Toggle the first toggle button.
buttons[0]->setToggleState(1);

// Print the index of the toggled button to show that the first button is toggled.
std::cout << toggleButtonGroup2D->getCurrentButtonIndex() << endl;